Security Assertion Markup Language (SAML) is an open standard that enables the exchange of security credentials between an identity provider and a service provider. This enables single sign-on, allowing the use of one set of credentials (for each user) to login to many different websites and web services. SAML is generally used to increase security and enhance user experience.
SAML can be used as the authentication provider in Pyramid. Start by selecting SAML as the authentication provider in the Admin console, and then define the SAML Settings and Initial User.
- Click here to see a specific guide for setting up ADFS SAML
- Click here to see a specific guide for setting up Azure SAML
Pyramid also supports integration with other SAML providers such as ForgeRock and OKTA.
Note: this feature is available with Enterprise licensing only.
Important: If Same Site client security is set to Strict when using SAML authentication, this may cause a loop redirect between Pyramid and the SAML provider, as cookies are prevented from working across different web domains.
SAML Flow
Each user must login once to the single sign-on with the identity provider. When the user tries to access the service provider, it sends an authorization and authentication request to the identity provider. The identity provider checks the user's credentials and determines whether the user is authorized to access the required service. If so, it sends a SAML assertion (an XML document) from the service provider, with the authorization and authentication messages.
SAML Setup
Start by selecting SAML as the authentication provider in the Admin console, and then define the settings and the principal name for the initial user. Then, you need to first register your Pyramid implementation with the SAML provider, to generate all the keys, tokens and access points for the authentication to operate.
General Settings
To setup a SAML provider to work with Pyramid, provide the following settings
- Consumer URL: This will be the Pyramid web site address that will be "called" back by the SAML provider. Typically this should be "https://myPyramidsite.com"
- SAML Issuer: the access token or identifier will be provided from the SAML provider to confirm the incoming application is Pyramid
- IDP URL: this the SAML provider's URL address - effectively the destination where the SAML request must be sent.
- Logout URL: The URL that the user is redirected to after successfully signing out of Pyramid.
- Active Directory Federation Services (ADFS): check this option to connect to ADFS. For more on ADFS click here.
Certificate
The (Base64) certificate is a signed certificate provided by the SAML provider to allow Pyramid to decrypt the assertion messages coming in from the IDP. The certificate is provided by the SAML provider itself. This is CRITICAL.
Initial User
This is the initial master user (from the SAML framework) that will be matched in Pyramid.
- User Name: the internal user name of the initial user. This is a bypass for the user when working outside of SAML.
- Password: the internal password for the user. Only required if manually logging in without the SAML framework.
- First Name: the first name of the initial user
- Last Name: the last name of the initial user
- Email: the email of the initial user
- Principal Name: the SAML login ID of the initial user typically in the format someone@domain.com. This is the critical element that will enable Pyramid to match the incoming SAML assertion with the user account.
Once SAML authentication is configured, access to Pyramid can be completed through a SAML token exchange with the designated SAML provider.